*788*The third item available from the ˙Info… dialog, Universal Methods, provides a way to access user-supplied comments comparable to the comments supplied about built-in primitives. If the method developer does not add a comment to a method icon in the Universal Methods window, the entry for that method in the ˙Info… dialog is empty. To provide *777*online documentation for the test method you just developed:
u Activate the Universal Methods window and Command-click the test method icon. An insertion bar begins flashing next to the test method icon, indicating that Prograph is ready to accept your typed comment.
u Type the following entry:
Inputs: none
Outputs: none
A nonsense method developed in the Prograph
tutorial to showcase a dataflow execution
error using the choose primitive.
*778*Although you are not required to do so, it is a good idea to create comments in a format similar to Prograph’s built-in, *781*online documentation. By supplying an input and output specification followed by a text description of the behavior of the method, you provide an easily accessible form of information to others who use your method in the future.
u Select*473* Universal Methods *1121*from the ˙Info… dialog and click the test item in the scrolling list that pops up. (The list is not actually scrolling, since this single item is the only selection available.) Your comment annotation from the Universal Methods window is displayed in the text pane of the dialog.
NOTE: The comment you added in the Universal Methods window is displayed in the ˙Info… dialog with the same line ending and carriage returns that you typed when the comment was added to the method icon.
If you want to supply long descriptive functional explanations of methods, the body of a paragraph entry should be one long line with no carriage returns. Then when comments are accessed from the ˙Info… dialog, the text pane’s own text wrapping presents a compact and complete display of the extended comment.
You may find that a Prograph text window with text wrap turned on is more useful for the preparation of comments. To open a text window select*632* New Text… *752*from the*369* File menu.
After you have finished a method description, copy and paste the text to the comment field of the method icon in the Universal Methods window. By saving the*923* text window in which these comments are developed, you then have a separate text file documenting your user-defined methods.
To see the utility of user-supplied class, attribute, and method comments:
u Open the file Association Class in the Ch 5 Δí folder (inside the Tutorial Examples Δí folder). (There is no need to keep the test method developed earlier, so simply click Discard when asked whether you want to save your current work before loading the new file.)
u When the file is fully loaded, the Association class icon is seen in the Classes window. Open the Universal Methods window, Command-click to create a new method icon, name it test, and then open its case window.
u Create an unspecified operation icon in the test case window and select *160* Classes from the ˙Info… dialog.
u Select the lone class item, Association, in the scrolling-list pane. The text pane displays a brief description of the nature and function of the Association class.
 
You can get further information about the structure and capabilities of a selected class by selecting Methods and Attributes from the ˙Info… dialog. (Notice that these two items are available only when you’ve selected a class.)
u Select Attributes to see information on the two attributes, key and value, of the Association class. Click each of the items in the scrolling list to review the acceptable values these attributes can take on, and read the brief description.
u Next, select Methods to see the list of available methods in the Association class. Take a minute or two to select each of the methods listed and review the input-output and functional specifications in the text pane of the dialog.
Just as you added notes to the test method earlier, the author of the Association class has supplied well-formatted, informative comments associated with each method icon in the Association class Methods window. In addition, the brief class description that is displayed when the class is selected is a user comment attached to the Association class icon in the Classes window.
NOTE: To take advantage of the ˙Info… dialog text-wrap capability in the text pane, the Association class author has used the format of a single long line for comments.
To see the comments you have just inspected in the text pane of the dialog, open the Association class Methods window. Select*178* Show Comments *447**645**985*from the Info menu—all comments of all methods in the active window are displayed. While not very readable in this view, they are well suited for display in the ˙Info… dialog. Select*175* Hide Comments *404**438*from*635* the Info menu before continuing. Activate the test universal method you were working on, reopen the ˙Info… dialog for classes, select Association, and then select*465* Methods.
u Click the item*161* key&value and read its input-output specification and functional description.
 
The description tells you that the left terminal of a key&value method operation icon requires a string or number input, while the right terminal can take any object or data type value as input. The root of this operation returns an instance of the Association class with its key and value attributes set to their respective inputs.
u Pull down the*471* Transfer *662**1108*pop-up menu. Notice that the last three items, normally disabled, are now available. These items let you select the type*708* of method referencing*453* (slash-prefixes)*452* you want to transfer, along with the method name*467*, to the operation being named.*4**5**455**1109**1110**1111**1113*
 
The*124* C/Name menu item prefixes the method name with the method’s class name and a slash character when it is transferred.
u Select C/Name to paste the formatted *693**694**695*method*751* reference and*707* name into the unspecified method operation icon in the test universal method. When the test method case window reactivates, press Return to accept the name transferred from the dialog. The operation icon now reads Association/key&value and is formatted with two terminals and a single root.
Prograph method case diagrams are a form of high-level documentation as well as being the source code*724* for the method itself.
u Double-click the operation’s right click spot (the diagonal patterned area to the right of the name text field). The case window for the key&value method immediately opens and is activated.
 
Inspecting the method, you confirm that the key&value method works in the manner described in the ˙Info… dialog. When you close the key&value case window, the test method case window is again the active, top window with the key&value operation icon selected.
Interactively using the ˙Info… dialog and popping up case windows of called methods are both useful techniques when developing new Prograph methods. The Primitives and Classes items provide significant online help and information (especially when user-developed classes are well commented), reducing your need to turn to external sources of information such as this manual and*488* Inside Macintosh.
Further, using the ˙Info… dialog reduces program errors that result from typing mistakes and lapses in memory of method and attribute names.
NOTE: Using the ˙Info… dialog to explore the available *454*attributes and methods of a class can be useful even when the class author has not supplied extensive comments like those in the Association class. Select a desired attribute or method, and then select Name to fill in the name of an operation icon in the method you are currently specifying. A quick double-click on the icon opens the referenced method’s own case window or, in a Get or Set operation, it shows the default value assigned to the referenced attribute. Dataflow-method *238*diagrams help you understand the requirements and performance of a method, and you can reduce errors*1095* in your work by using the ˙Info… dialog.
The information for*468* Persistents *828*is similar in appearance and function to that for*473* Universal Methods. Any online help or information available must be user-supplied. Comments are attached to the Persistent icon in the Persistents window in the same way that comments are added to icons in the Classes, Universal, and class Methods*716* windows.
t Macintosh Online Information
*464**558*The last five items in the Category pop-up menu in the ˙Info… dialog provide online information about Macintosh methods*461**545*, constants*458*, globals*460**544*, structures*463**547*, and fields*459**543*.
 
The information provided for these Mac items is relatively cursory. Most Prograph programming you do will be developed under Application Builder using Prograph primitives and System classes. System class instances and Prograph primitives provide high-level access to the Macintosh ROM and other Macintosh operating-system facilities. You do not have to manage directly the inner complexities of your machine in order to write sophisticated Macintosh applications.
*782*However, if you are a “Mac hack” and have a copy of Inside Macintosh or another reference to the underpinnings of the Mac, you can fully and completely control the interface between your Prograph application and the Macintosh hardware; see *934*Reference chapter 7, “The Macintosh Toolbox,*559*” for more information. You can also find more about the use of Macintosh*929* QuickDraw ROM routines in the Application Builder tutorial on using graphics in*125* Canvas objects.
